5ba59c5c9781b8d8915f7075d680f834d43a4315
3 * @defgroup FileJournal File journal
8 * File operation journaling.
10 * This program is free software; you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; either version 2 of the License, or
13 * (at your option) any later version.
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
20 * You should have received a copy of the GNU General Public License along
21 * with this program; if not, write to the Free Software Foundation, Inc.,
22 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
23 * http://www.gnu.org/copyleft/gpl.html
26 * @ingroup FileJournal
30 * @brief Class for handling file operation journaling.
32 * Subclasses should avoid throwing exceptions at all costs.
34 * @ingroup FileJournal
37 abstract class FileJournal
{
45 * Construct a new instance from configuration.
47 * @param array $config Includes:
48 * 'ttlDays' : days to keep log entries around (false means "forever")
50 protected function __construct( array $config ) {
51 $this->ttlDays
= isset( $config['ttlDays'] ) ?
$config['ttlDays'] : false;
55 * Create an appropriate FileJournal object from config
57 * @param array $config
58 * @param string $backend A registered file backend name
62 final public static function factory( array $config, $backend ) {
63 $class = $config['class'];
64 $jrn = new $class( $config );
65 if ( !$jrn instanceof self
) {
66 throw new InvalidArgumentException( "Class given is not an instance of FileJournal." );
68 $jrn->backend
= $backend;
74 * Get a statistically unique ID string
76 * @return string <9 char TS_MW timestamp in base 36><22 random base 36 chars>
78 final public function getTimestampedUUID() {
80 for ( $i = 0; $i < 5; $i++
) {
81 $s .= mt_rand( 0, 2147483647 );
83 $s = Wikimedia\base_convert
( sha1( $s ), 16, 36, 31 );
85 return substr( Wikimedia\base_convert
( wfTimestamp( TS_MW
), 10, 36, 9 ) . $s, 0, 31 );
89 * Log changes made by a batch file operation.
91 * @param array $entries List of file operations (each an array of parameters) which contain:
92 * op : Basic operation name (create, update, delete)
93 * path : The storage path of the file
94 * newSha1 : The final base 36 SHA-1 of the file
95 * Note that 'false' should be used as the SHA-1 for non-existing files.
96 * @param string $batchId UUID string that identifies the operation batch
99 final public function logChangeBatch( array $entries, $batchId ) {
100 if ( !count( $entries ) ) {
101 return StatusValue
::newGood();
104 return $this->doLogChangeBatch( $entries, $batchId );
108 * @see FileJournal::logChangeBatch()
110 * @param array $entries List of file operations (each an array of parameters)
111 * @param string $batchId UUID string that identifies the operation batch
112 * @return StatusValue
114 abstract protected function doLogChangeBatch( array $entries, $batchId );
117 * Get the position ID of the latest journal entry
121 final public function getCurrentPosition() {
122 return $this->doGetCurrentPosition();
126 * @see FileJournal::getCurrentPosition()
129 abstract protected function doGetCurrentPosition();
132 * Get the position ID of the latest journal entry at some point in time
134 * @param int|string $time Timestamp
137 final public function getPositionAtTime( $time ) {
138 return $this->doGetPositionAtTime( $time );
142 * @see FileJournal::getPositionAtTime()
143 * @param int|string $time Timestamp
146 abstract protected function doGetPositionAtTime( $time );
149 * Get an array of file change log entries.
150 * A starting change ID and/or limit can be specified.
152 * @param int $start Starting change ID or null
153 * @param int $limit Maximum number of items to return
154 * @param string &$next Updated to the ID of the next entry.
155 * @return array List of associative arrays, each having:
156 * id : unique, monotonic, ID for this change
157 * batch_uuid : UUID for an operation batch
158 * backend : the backend name
159 * op : primitive operation (create,update,delete,null)
160 * path : affected storage path
161 * new_sha1 : base 36 sha1 of the new file had the operation succeeded
162 * timestamp : TS_MW timestamp of the batch change
163 * Also, $next is updated to the ID of the next entry.
165 final public function getChangeEntries( $start = null, $limit = 0, &$next = null ) {
166 $entries = $this->doGetChangeEntries( $start, $limit ?
$limit +
1 : 0 );
167 if ( $limit && count( $entries ) > $limit ) {
168 $last = array_pop( $entries ); // remove the extra entry
169 $next = $last['id']; // update for next call
171 $next = null; // end of list
178 * @see FileJournal::getChangeEntries()
183 abstract protected function doGetChangeEntries( $start, $limit );
186 * Purge any old log entries
188 * @return StatusValue
190 final public function purgeOldLogs() {
191 return $this->doPurgeOldLogs();
195 * @see FileJournal::purgeOldLogs()
196 * @return StatusValue
198 abstract protected function doPurgeOldLogs();